*************************************************************************
* Myricom MX networking software and documentation                      *
* Copyright (c) 2004 by Myricom, Inc.                                   *
* All rights reserved.  See the file `COPYING' for copyright notice.    *
*************************************************************************

README for MX Utility Functions and MX Test Suite and Benchmark Programs

Table of Contents:
-----------------

  I. Introduction
 II. Running the MX Tool/Utility Functions
III. Running the MX Test Suite
 IV. Running the MX Benchmark Programs

************************************************************************
If difficulties are encountered, please consult the FAQ
         http://www.myri.com/scs/FAQ/
and all technical support questions should be directed to help@myri.com.
************************************************************************

  I.  Introduction

      The <install_path>/bin subdirectory contains the following MX 
      utility/tool functions:

      mx_counters
      mx_dmabench
      mx_endpoint_info
      mx_hostname
      mx_info

      as well as the subdirectory <install_path>/bin/tests, which
      contains the MX Test Suite and Benchmark Programs.

      The MX Benchmark Programs are:

      mx_pingpong
      mx_pingpong_unex
      mx_stream


 II.  Running the MX Tool/Utility Functions

      cd <install_path>/bin

      ./mx_counters

         `mx_counters' displays diagnostic statistics about the operation 
         of the Myrinet interface.  This program is used almost exclusively 
         for problem diagnosis.

      ./mx_dmabench

         `mx_dmabench' performs a hardware benchmark test of the PCI bus
         with the DMA engine of the Myrinet interface. The output of
         this command gives the maximum sustained bandwidth that can
         be obtained from the PCI bus.

      ./mx_endpoint_info

         `mx_endpoint_info' displays information about the status of 
         the MX endpoints.  If an MX endpoint is in use, it tells you
         the PID of the job, the name of the executable, and Info.

         interfaces on this host and the status of its MX endpoints.
         It  also displays the total number of hosts with which it can
         communicate, and routing table information to each respective
         Myrinet interface in the network.

      ./mx_hostname 

      `mx_hostname' forces the setting of the MX hostname. mx_hostname -c 
       clears the cache of hostnames of the Myrinet fabric and restarts
       the hostname resolution phase.

      ./mx_info

         `mx_info' displays information about the detected Myrinet cards
	 and routing information to all of the nodes with which they
         can communicate.

      For a list of all possible runtime options for these commands, you
      can issue the command with -help as the runtime option, e.g.,
      ./mx_counters -help.


III.  Running the MX Test Suite

      After installing MX, as described in the <MX_source_dir>/README,
      you should then run the MX Test Suite.

      First of all, check to make sure that the entire Myrinet network
      has been mapped, by typing

      cd <install_path>/bin
      ./mx_info

      If you see all of your hostnames resolved in your cluster and
      routing bits listed next to each, then the mapping of the
      Myrinet network has been completed and you are ready to run the
      MX Test Suite.

      cd <install_path>/bin/tests

      This directory contains mono-processus and bi-processus test programs.

      Mono-processus tests:

      mx_cancel_test
      mx_decompose_test
      mx_ibuffered_test
      mx_ipeek_test
      mx_iprobe_test
      mx_isend_test
      mx_large_align
      mx_loopback_test
      mx_status_test
      mx_vect_test

      Bi-processus tests:
 
      mx_iconnect_test
      mx_peek_test
      mx_unexpected_test
      mx_wait_any_test
      mx_wakeup_test

      To run these tests between two hosts, 
      type, for example, (on the first host)

      ./mx_peek_test

      and then type the following command on the second host:

      ./mx_peek_test -d <hostname>:0

      where <hostname> is the hostname of the first host.

 IV.  Running the MX Benchmark Programs

      cd <install_path>/bin/tests

      a.  mx_pingpong

          mx_pingpong does a PingPong without unexpected messages.
  
          To test PingPong latency and bandwidth between two hosts, 
          type (on the first host)

          ./mx_pingpong

          and then type the following command on the second host:

          ./mx_pingpong -d <hostname>:0

          where <hostname> is the hostname of the first host.

      b.  mx_pingpong_unex

          mx_pingpong_unex is equivalent to Pallas PingPong.

          To test PingPong latency and bandwidth between two hosts, 
          type (on the first host)

          ./mx_pingpong_unex

          and then type the following command on the second host:

          ./mx_pingpong_unex -d <hostname>:0

          where <hostname>:0 is the hostname of the first host.

      c.  mx_stream

          mx_stream does a stream/spray of sends, and is useful
          for demonstrating the pipeline in MX.

          To test mx_stream between two hosts, type (on the first host)

          ./mx_stream

          and then type the following command on the second host:

          ./mx_stream -d <hostname>:0

          where <hostname> is the hostname of the first host.
